home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / brkiter.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  15KB  |  378 lines
  1. /*
  2. *****************************************************************************************
  3. *                                                                                       *
  4. * COPYRIGHT:                                                                            *
  5. *   (C) Copyright Taligent, Inc.,  1997                                                 *
  6. *   (C) Copyright International Business Machines Corporation,  1997-1999               *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.                  *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure             *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                              *
  10. *                                                                                       *
  11. *****************************************************************************************
  12. *
  13. * File BRKITER.H
  14. *
  15. * Modification History:
  16. *
  17. *   Date        Name        Description
  18. *   02/18/97    aliu        Added typedef for TextCount.  Made DONE const.
  19. *   05/07/97    aliu        Fixed DLL declaration.
  20. *   07/09/97    jfitz       Renamed BreakIterator and interface synced with JDK
  21. *   08/11/98    helena      Sync-up JDK1.2.
  22. *****************************************************************************************
  23. */
  24.  
  25. #ifndef BRKITER_H
  26. #define BRKITER_H
  27.  
  28.  
  29. #include "unistr.h"
  30. #include "chariter.h"
  31. #include "locid.h"
  32.  
  33.  
  34. //class Locale;
  35.  
  36. /**
  37.  * The BreakIterator class implements methods for finding the location
  38.  * of boundaries in text. BreakIterator is an abstract base class.
  39.  * Instances of BreakIterator maintain a current position and scan over
  40.  * text returning the index of characters where boundaries occur.
  41.  * <P>
  42.  * Line boundary analysis determines where a text string can be broken
  43.  * when line-wrapping. The mechanism correctly handles punctuation and
  44.  * hyphenated words.
  45.  * <P>
  46.  * Sentence boundary analysis allows selection with correct
  47.  * interpretation of periods within numbers and abbreviations, and
  48.  * trailing punctuation marks such as quotation marks and parentheses.
  49.  * <P>
  50.  * Word boundary analysis is used by search and replace functions, as
  51.  * well as within text editing applications that allow the user to
  52.  * select words with a double click. Word selection provides correct
  53.  * interpretation of punctuation marks within and following
  54.  * words. Characters that are not part of a word, such as symbols or
  55.  * punctuation marks, have word-breaks on both sides.
  56.  * <P>
  57.  * Character boundary analysis allows users to interact with
  58.  * characters as they expect to, for example, when moving the cursor
  59.  * through a text string. Character boundary analysis provides correct
  60.  * navigation of through character strings, regardless of how the
  61.  * character is stored.  For example, an accented character might be
  62.  * stored as a base character and a diacritical mark. What users
  63.  * consider to be a character can differ between languages.
  64.  * <P>
  65.  * This is the interface for all text boundaries.
  66.  * <P>
  67.  * Examples:
  68.  * <P>
  69.  * Helper function to output text
  70.  * <pre>
  71.  * .   void printTextRange( BreakIterator& iterator, UTextOffset start, UTextOffset end )
  72.  * .   {
  73.  * .       UnicodeString textBuffer, temp;
  74.  * .       CharacterIterator *strIter = iterator.createText();
  75.  * .       strIter->getText(temp);
  76.  * .       cout << " " << start << " " << end << " |" 
  77.  * .            << temp.extractBetween(start, end, textBuffer)
  78.  * .            << "|" << endl;
  79.  * .       delete strIter;
  80.  * .   }
  81.  * </pre>
  82.  * Print each element in order:
  83.  * <pre>
  84.  * .   void printEachForward( BreakIterator& boundary)
  85.  * .   {
  86.  * .      UTextOffset start = boundary.first();
  87.  * .      for (UTextOffset end = boundary.next();
  88.  * .        end != BreakIterator::DONE;
  89.  * .        start = end, end = boundary.next())
  90.  * .        {
  91.  * .            printTextRange( boundary, start, end );
  92.  * .        }
  93.  * .   }
  94.  * </pre>
  95.  * Print each element in reverse order:
  96.  * <pre>
  97.  * .   void printEachBackward( BreakIterator& boundary)
  98.  * .   {
  99.  * .      UTextOffset end = boundary.last();
  100.  * .      for (UTextOffset start = boundary.previous();
  101.  * .        start != BreakIterator::DONE;
  102.  * .        end = start, start = boundary.previous())
  103.  * .        {
  104.  * .            printTextRange( boundary, start, end );
  105.  * .        }
  106.  * .   }
  107.  * </pre>
  108.  * Print first element
  109.  * <pre>
  110.  * .   void printFirst(BreakIterator& boundary)
  111.  * .   {
  112.  * .       UTextOffset start = boundary.first();
  113.  * .       UTextOffset end = boundary.next();
  114.  * .       printTextRange( boundary, start, end );
  115.  * .   }
  116.  * </pre>
  117.  * Print last element
  118.  * <pre>
  119.  * .   void printLast(BreakIterator& boundary)
  120.  * .   {
  121.  * .       UTextOffset end = boundary.last();
  122.  * .       UTextOffset start = boundary.previous();
  123.  * .       printTextRange( boundary, start, end );
  124.  * .   }
  125.  * </pre>
  126.  * Print the element at a specified position
  127.  * <pre>
  128.  * .   void printAt(BreakIterator &boundary, UTextOffset pos )
  129.  * .   {
  130.  * .       UTextOffset end = boundary.following(pos);
  131.  * .       UTextOffset start = boundary.previous();
  132.  * .       printTextRange( boundary, start, end );
  133.  * .   }
  134.  * </pre>
  135.  * Creating and using text boundaries
  136.  * <pre>
  137.  * .      void BreakIterator_Example( void )
  138.  * .      {
  139.  * .          BreakIterator* boundary;
  140.  * .          UnicodeString stringToExamine("Aaa bbb ccc. Ddd eee fff.");
  141.  * .          cout << "Examining: " << stringToExamine << endl;
  142.  * .
  143.  * .          //print each sentence in forward and reverse order
  144.  * .          boundary = BreakIterator::createSentenceInstance( Locale::US );
  145.  * .          boundary->setText(&stringToExamine);
  146.  * .          cout << "----- forward: -----------" << endl;
  147.  * .          printEachForward(*boundary);
  148.  * .          cout << "----- backward: ----------" << endl;
  149.  * .          printEachBackward(*boundary);
  150.  * .          delete boundary;
  151.  * .
  152.  * .          //print each word in order
  153.  * .          boundary = BreakIterator::createWordInstance();
  154.  * .          boundary->setText(&stringToExamine);
  155.  * .          cout << "----- forward: -----------" << endl;
  156.  * .          printEachForward(*boundary);
  157.  * .          //print first element
  158.  * .          cout << "----- first: -------------" << endl;
  159.  * .          printFirst(*boundary);
  160.  * .          //print last element
  161.  * .          cout << "----- last: --------------" << endl;
  162.  * .          printLast(*boundary);
  163.  * .          //print word at charpos 10
  164.  * .          cout << "----- at pos 10: ---------" << endl;
  165.  * .          printAt(*boundary, 10 );
  166.  * .
  167.  * .          delete boundary;
  168.  * .      }
  169.  * </pre>
  170.  */
  171. class U_I18N_API BreakIterator {
  172. public:
  173.     virtual ~BreakIterator();
  174.  
  175.     /**
  176.      * Return true if another object is semantically equal to this
  177.      * one. The other object should be an instance of the same subclass of
  178.      * BreakIterator. Objects of different subclasses are considered
  179.      * unequal.
  180.      * <P>
  181.      * Return true if this BreakIterator is at the same position in the
  182.      * same text, and is the same class and type (word, line, etc.) of
  183.      * BreakIterator, as the argument.  Text is considered the same if
  184.      * it contains the same characters, it need not be the same
  185.      * object, and styles are not considered.
  186.      */
  187.     virtual bool_t operator==(const BreakIterator&) const = 0;
  188.  
  189.     bool_t operator!=(const BreakIterator& rhs) const { return !operator==(rhs); }
  190.  
  191.     /**
  192.      * Return a polymorphic copy of this object.  This is an abstract
  193.      * method which subclasses implement.
  194.      */
  195.     virtual BreakIterator* clone(void) const = 0;
  196.  
  197.     /**
  198.      * Return a polymorphic class ID for this object. Different subclasses
  199.      * will return distinct unequal values.
  200.      */
  201.     virtual UClassID getDynamicClassID(void) const = 0;
  202.  
  203.     /**
  204.      * Get the text for which this object is finding the boundaries.
  205.      */
  206.     virtual CharacterIterator* createText(void) const = 0;
  207.  
  208.     /**
  209.      * Change the text over which this operates. The text boundary is
  210.      * reset to the start.
  211.      */
  212.     virtual void  setText(const UnicodeString* it) = 0;
  213.  
  214.     /**
  215.      * Change the text over which this operates. The text boundary is
  216.      * reset to the start.
  217.      */
  218.     virtual void  adoptText(CharacterIterator* it) = 0;
  219.  
  220.     /**
  221.      * DONE is returned by previous() and next() after all valid
  222.      * boundaries have been returned.
  223.      */
  224.     static const UTextOffset DONE;
  225.  
  226.     /**
  227.      * Return the index of the first character in the text being scanned.
  228.      */
  229.     virtual UTextOffset first(void) = 0;
  230.  
  231.     /**
  232.      * Return the index immediately BEYOND the last character in the text being scanned.
  233.      */
  234.     virtual UTextOffset last(void) = 0;
  235.  
  236.     /**
  237.      * Return the boundary preceding the current boundary.
  238.      * @return The character index of the previous text boundary or DONE if all
  239.      * boundaries have been returned.
  240.      */
  241.     virtual UTextOffset previous(void) = 0;
  242.  
  243.     /**
  244.      * Return the boundary following the current boundary.
  245.      * @return The character index of the next text boundary or DONE if all
  246.      * boundaries have been returned.
  247.      */
  248.     virtual UTextOffset next(void) = 0;
  249.  
  250.     /**
  251.      * Return character index of the text boundary that was most recently
  252.      * returned by next(), previous(), first(), or last()
  253.      * @return The boundary most recently returned.
  254.      */
  255.     virtual UTextOffset current(void) const = 0;
  256.  
  257.     /**
  258.      * Return the first boundary following the specified offset.
  259.      * The value returned is always greater than the offset or
  260.      * the value BreakIterator.DONE
  261.      * @param offset the offset to begin scanning.
  262.      * @return The first boundary after the specified offset.
  263.      */
  264.     virtual UTextOffset following(UTextOffset offset) = 0;
  265.  
  266.     /**
  267.      * Return the first boundary preceding the specified offset.
  268.      * The value returned is always smaller than the offset or
  269.      * the value BreakIterator.DONE
  270.      * @param offset the offset to begin scanning.
  271.      * @return The first boundary before the specified offset.
  272.      */
  273.     virtual UTextOffset preceding(UTextOffset offset) = 0;
  274.  
  275.     /**
  276.      * Return true if the specfied position is a boundary position.
  277.      * @param offset the offset to check.
  278.      * @return True if "offset" is a boundary position.
  279.      */
  280.     virtual bool_t isBoundary(UTextOffset offset) = 0;
  281.  
  282.     /**
  283.      * Return the nth boundary from the current boundary
  284.      * @param n which boundary to return.  A value of 0
  285.      * does nothing.  Negative values move to previous boundaries
  286.      * and positive values move to later boundaries.
  287.      * @return The index of the nth boundary from the current position, or
  288.      * DONE if there are fewer than |n| boundaries in the specfied direction.
  289.      */
  290.     virtual UTextOffset next(int32_t n) = 0;
  291.  
  292.     /**
  293.      * Create BreakIterator for word-breaks using the given locale.
  294.      * Returns an instance of a BreakIterator implementing word breaks.
  295.      * WordBreak is useful for word selection (ex. double click)
  296.      * @param where the locale. If a specific WordBreak is not
  297.      * avaliable for the specified locale, a default WordBreak is returned.
  298.      * @return A BreakIterator for word-breaks
  299.      */
  300.     static BreakIterator* createWordInstance(const Locale& where = Locale::getDefault());
  301.  
  302.     /**
  303.      * Create BreakIterator for line-breaks using specified locale.
  304.      * Returns an instance of a BreakIterator implementing line breaks. Line
  305.      * breaks are logically possible line breaks, actual line breaks are
  306.      * usually determined based on display width.
  307.      * LineBreak is useful for word wrapping text.
  308.      * @param where the locale. If a specific LineBreak is not
  309.      * avaliable for the specified locale, a default LineBreak is returned.
  310.      * @return A BreakIterator for line-breaks
  311.      */
  312.     static BreakIterator* createLineInstance(const Locale& where = Locale::getDefault());
  313.  
  314.     /**
  315.      * Create BreakIterator for character-breaks using specified locale
  316.      * Returns an instance of a BreakIterator implementing character breaks.
  317.      * Character breaks are boundaries of combining character sequences.
  318.      * @param where the locale. If a specific character break is not
  319.      * avaliable for the specified locale, a default character break is returned.
  320.      * @return A BreakIterator for character-breaks
  321.      */
  322.     static BreakIterator* createCharacterInstance(const Locale& where = Locale::getDefault());
  323.  
  324.     /**
  325.      * Create BreakIterator for sentence-breaks using specified locale
  326.      * Returns an instance of a BreakIterator implementing sentence breaks.
  327.      * @param where the locale. If a specific SentenceBreak is not
  328.      * avaliable for the specified locale, a default SentenceBreak is returned.
  329.      * @return A BreakIterator for sentence-breaks
  330.      */
  331.     static BreakIterator* createSentenceInstance(const Locale& where = Locale::getDefault());
  332.  
  333.     /**
  334.      * Get the set of Locales for which TextBoundaries are installed
  335.      * @param count the output parameter of number of elements in the locale list
  336.      * @return available locales
  337.      */
  338.     static const Locale* getAvailableLocales(int32_t& count);
  339.  
  340.     /**
  341.      * Get name of the object for the desired Locale, in the desired langauge.
  342.      * @param objectLocale must be from getAvailableLocales.
  343.      * @param displayLocale specifies the desired locale for output.
  344.      * @param name the fill-in parameter of the return value
  345.      * Uses best match.
  346.      * @return user-displayable name
  347.      */
  348.     static UnicodeString& getDisplayName(const Locale& objectLocale,
  349.                                          const Locale& displayLocale,
  350.                                          UnicodeString& name);
  351.  
  352.     /**
  353.      * Get name of the object for the desired Locale, in the langauge of the
  354.      * default locale.
  355.      * @param objectLocale must be from getMatchingLocales
  356.      * @param name the fill-in parameter of the return value
  357.      * @return user-displayable name
  358.      */
  359.     static UnicodeString& getDisplayName(const Locale& objectLocale,
  360.                                          UnicodeString& name);
  361.  
  362.  
  363.  
  364. protected:
  365.     BreakIterator();
  366.  
  367. private:
  368.     /**
  369.      * The copy constructor and assignment operator have no real implementation.
  370.      * They are provided to make the compiler happy. Do not call.
  371.      */
  372.     BreakIterator& operator=(const BreakIterator& other) { return *this; }
  373.     BreakIterator (const BreakIterator& other) {}
  374. };
  375.  
  376. #endif // _BRKITER
  377. //eof
  378.